2.3. Using Parameters
To find which parameters you can use with a cmdlet, type either Get-Help <cmdlet> or Get-Command <cmdlet> -syntax, where <cmdlet>
is the name of the cmdlet you want parameter information about. For
example, Get-Help New-SPSite or Get-Command New-SPSite –syntax
will provide you with information about the parameters associated with
New-SPSite. The Get-Help cmdlet also has several parameters associated
with it, and depending on the amount of information you want, you can
use them with the Get-Help command. If you know a cmdlet very well and
do not want a descriptive explanation of what the cmdlet does, then you
may simply want to see some examples of how to use the cmdlet, in which
case you would type Get-Help New-SPSite –examples.
To learn about which
parameters to use with a cmdlet, review the syntax section of the help
results, as shown in the following output. Optional parameters are
enclosed within square brackets ([ ]) and the values to be passed to the parameters are enclosed within angled brackets (<>). The following example shows the syntax section of the Get-SPSite cmdlet.
SYNTAX
Get-SPSite [-AssignmentCollection <SPAssignmentCollection>]
[-Confirm [<SwitchParameter>]] [-Filter <ScriptBlock>] [-Limit <String>]
[-WebApplication <SPWebApplicationPipeBind>] [-WhatIf [<SwitchParameter>]]
[<CommonParameters>]
Get-SPSite -Identity <SPSitePipeBind> [-AssignmentCollection
<SPAssignmentCollection>] [-Confirm [<SwitchParameter>]] [-Filter <ScriptBlock>]
[-Limit <String>] [-Regex <SwitchParameter>] [-WhatIf [<SwitchParameter>]]
[<CommonParameters>]
Get-SPSite -ContentDatabase <SPContentDatabasePipeBind> [-AssignmentCollection
<SPAssignmentCollection>] [-Confirm [<SwitchParameter>]] [-Filter <ScriptBlock>]
[-Limit <String>] [-WhatIf [<SwitchParameter>]] [<CommonParameters>]
Get-SPSite -SiteSubscription <SPSiteSubscriptionPipeBind> [-AssignmentCollection
<SPAssignmentCollection>] [-Confirm [<SwitchParameter>]] [-Filter <ScriptBlock>]
[-Limit <String>] [-WhatIf [<SwitchParameter>]] [<CommonParameters>]
Notice that there are four ways to use Get-SPSite, and each syntax has an –AssignmentCollection parameter. The –AssignmentCollection
parameter relates to an important aspect of the built-in SharePoint
cmdlet, which is examined in more detail in the sidebar titled Memory Considerations When Using Windows PowerShell.
The first syntax example
shown in the listing above has no mandatory parameter, so the
Get-SPSite cmdlet would have a scope of the farm or Web application.
The other three syntaxes have a mandatory parameter that defines the
scope as site collection, content database, or collection of site
collections that subscribe to shared settings, features, and services,
as shown in the following code. As is the case with the other SPSite
cmdlets, in a large installation, this cmdlet could output a large
amount of information, and the queries to many content databases could
severely affect the performance of the SharePoint servers. Therefore,
by default, the output reports only on the first 20 objects.
You can alter this output limit by using the –limit
parameter, as shown in the following example, which outputs all site
collections that are stored in the Contoso_TeamsDB content database.
Get-SPSite -ContentDatabase Contoso_TeamsDB -limit all
You can provide the values for these scope parameters, or in the case of the –identity parameter, where the value is a URL, you can use the wildcard character (*). The default help with no parameter provides a limited description of the command.
For more information, use the –detailed or the –full parameter. The –full parameter provides additional information about the parameters. For example, additional information about the –identity parameter is shown on the following page.
PARAMETERS
-Identity <SPSitePipeBind>
Specifies the URL or GUID of the site collection to get.
The type must be a valid URL, in the form http://server_name or http://
server_name/sites/sitename, or a valid GUID (for example, 12345678-90ab
-cdef-1234-567890bcdefgh).
Required? true
Position? 1
Default value
Accept pipeline input? True
Accept wildcard characters? false
If you look at the last five lines of the output, you see that it provides more information on how to use the –identity parameter. For example, the required value is equal to True, which indicates that the –identity
parameter is a mandatory parameter for the Get-SPSite cmdlet. However,
the position value is equal to 1, which means that if you place a URL
of a site collection immediate after the Get-SPSite cmdlet, you do not
have to use the –identity
parameter because the URL will be read as the identity (URL) of a site
collection, where all the property values for site collections that
exist under the personal managed path are displayed, as shown in the
following example.
Get-SPSite http://MySite/personal/* | Select *
Many of the parameters have a
value enclosed in angle brackets, with the suffix PipeBind. This
indicates that the parameter can accept an object variable of a
specific type. For example, [–ContentDatabase
<SPContentDatabasePipeBind>] means that the –ContentDatabase
parameter can accept a SharePoint content database object, and this
object can be passed to the ContentDatabase object either as a
variable, or it can be piped in from the results of another cmdlet.
When you pipe an object into a cmdlet, you do not need to type or use a
variable. When you pipe an object from one cmdlet into another cmdlet,
you do not have to specify the parameter, because Windows PowerShell
checks the type of object and will match it to the correct parameter.
The following example lists all site collections that are stored in any
content databases that have the characters oso anywhere in their names.
Get-SPContentDatabase | where {$_.name -match "oso"} | Get-SPSite -Limit 50
Get-SPContentDatabase returns
a collection of content databases, and then you need to check each
content database to see if it matches our condition. The Where-object
cmdlet, which has the aliases where or ?, acts like a loop, so it will
check each content database object returned from the Get-SPContentDatabase
cmdlet. The variable $_ represents one content database object, and
.name is the content database property that needs to be matched for our
query. The operator is –match.
Windows PowerShell has a number of operators, such as –eq (equal to), –ne (not equal to), –lt (less than), –ge (greater than or equal to), –like (matches a wildcard pattern), and –notlike (does not match a wildcard pattern). The –like, –notlike, –match, and –notmatch operators are used for pattern matching. The –match and –notmatch operators use regular expressions to determine whether a value does or does not contain a match for an expression.
An alternative method to use instead of a WHERE statement is the –filter parameter, which uses the same syntax as the WHERE statement and can produce the same results. However, the –filter
parameter executes on the server. Piping the results of the
Get-SPContentDatabase cmdlet to the WHERE statement causes a SQL round
trip to wherever the Windows PowerShell client is running. Using the –filter
parameter can result in a faster performance, allowing the command to
leverage the filtering abilities of SQL instead of attempting a local
search. However, when you use the –filter
parameter, only the Owner, SecondaryOwner, and LockState properties can
be accessed for SPSite cmdlets. A number of cmdlets have other parameters
that allow you to filter the resulting output. For example, SPWeb
provides parameters to filter output on the template or title of the
site (web). Still, in many cases the –filter parameter can save you time—for example, finding all the blog sites in a farm of 4300 webs takes about 1.2 seconds with the –filter parameter, but it takes approximately 15 minutes if you use a WHERE statement. Following are several examples that use the –filter parameter.
This example returns all site collections whose primary owner has the username peter.
Get-SPSite -Filter {$_.Owner -eq "contoso\peter"}
This example returns all websites in the http://teams/sites/HR site collection that were created using the Blank Meeting Workspace template.
Get-SPSite http://teams/sites/HR | Get-SPWeb -Filter {$_.Template -eq "STS#03"}
Note:
When you create a new site
collection, if you do not specify a template or the template cannot be
found, then you will need to create a website as the root of the site
collection. You can do this by using the New-SPWeb command or by
selecting the appropriate site template when you display the site
collection for the first time in the browser.
To find details of the templates installed, together with the appropriate template ids, use the Get-SPWebTemplate cmdlet. A sample of the output of this command is shown here.
Name Title LocaleId Custom
---- ----- -------- ------
GLOBAL#0 Global template 1033 False
STS#0 Team Site 1033 False
STS#1 Blank Site 1033 False
STS#2 Document Workspace 1033 False
MPS#0 Basic Meeting Workspace 1033 False
MPS#1 Blank Meeting Workspace 1033 False
MPS#2 Decision Meeting Workspace 1033 False
MPS#3 Social Meeting Workspace 1033 False
MPS#4 Multipage Meeting Workspace 1033 False
CENTRALADMIN#0 Central Admin Site 1033 False
WIKI#0 Wiki Site 1033 False
BLOG#0 Blog 1033 False
SGS#0 Group Work Site 1033 False
TENANTADMIN#0 Tenant Admin Site 1033 False
ACCSRV#0 Access Services Site 1033 False
ACCSRV#1 Assets Web Database 1033 False
ACCSRV#3 Charitable Contributions Web Database 1033 False
On the Get-SPSite and Get-SPSiteAdministration,
provide two other filters that use the SQL-driven filtering: the
“Wildcard URLs” and regular expression (–RegEx) parameter, for example:
Get-SPSite http://intranet/sites/*
Get-SPSite "http://intranet/(sites|teams)/HR" -RegEx
|
The default
behavior of Windows PowerShell is that it runs a multithread
environment and that each line, function, or script runs in its own
thread ($host.Runspace.ThreadOptions == “Default”). The SharePoint 2010 Management Shell runs each
line, function, or script in the first thread
($host.Runspace.ThreadOptions =“ReuseThread”), which mitigates the
problem—but memory leaks can still occur. Hence, the two SharePoint
cmdlets that you should learn to use are the Start-SPAssignment and the Stop-SPAssignment. These relate to the –SPAssignmentCollection
parameter that you may see used with a number of SharePoint cmdlets to
return a “disposable object.” In developer-speak, these are objects
that implement the IDisposable
Interface. If these objects are not disposed of correctly, they can
cause memory leaks. In particular, this relates to the SPSite, SPWeb,
and SPSiteAdministration objects. If you use cmdlets associated with these objects in one pipe and don’t use variables to store the objects, the memory
used is automatically disposed of at the end of a pipe. If you have a
long pipe that obtains many objects, this can cause a shortage of
memory on your SharePoint server, which then can have a noticeable
effect on requests for pages from that server.
When you store any of
the three objects in a variable, you then have to dispose of the memory
assigned to that object. The following examples show the main methods
of using these objects with variables and how to dispose of the memory.
Use the simple
method of using the SPAssignment cmdlets, in which all objects are kept
in a global memory store that is released when the Stop-SPAssignment cmdlet is called. Start-SPAssignment -Global
$sc = Get-SPSite http://intranet
$sc.Title
Stop-SPAssignment -Global
Use the advanced
method of using the SPAssignment cmdlet and tell it to track memory
assigned to a specific variable. In the following example, the Start-SPAssignment
cmdlet creates a named store that is pointed to by $o, and the variable
$sc is associated with that named store and populated with information
about the Internet site collection object. The Stop-SPAssignment cmdlet
then releases the memory associated with the named store. $o = Start-SPAssignment
$sc = $o | Get-SPSite http://intranet
Get-SPSite -Limit all
$sc.Title
$o | Stop-SPAssignment
If you are used to
developing on the SharePoint platform, then you can use a similar
technique to that which you use in your code to overcome this issue.
For example, use variables within one Windows PowerShell line and dispose of them at the end of that line. $sc = New-SPSite("http://Intranet"); $sc.Title; $sc.Dispose()
This stores the site collection object in the variable $sc.
The next command then prints out the title of the intranet site
collection, and the last command releases the memory that stored the
site collection object.
Note:
This same command can be run safely using the following syntax.
New-SPSite(http://intranet) | Select Title
Be aware that the simple method of calling SPAssignment shown here also can cause memory
problems. Any object you obtain between the Stop and Stop SPAssignment
commands will be retained in the global assignment store and will not
be released until the Stop-SPAssignment cmdlet is executed, whereas
when you use the advanced method of calling SPAssignment, only the
memory associated with variables you ask SPAssignment to track will be
retained until the Stop-SPAssignment cmdlet is executed. Therefore, if
you need to view large amount of information as you complete a task,
and you do not want to starve the SharePoint server of memory, the
advanced method of using SPAssigment is preferable. Use Get-Help About_SPAssignment to find more information.
|
